Setting up and Configuring Nginx with Docker Compose

TLDR

• Nginx configuration files consist of Main, Events, and HTTP Contexts. It is recommended to place custom configurations in the /etc/nginx/conf.d/ directory.
• location matching priority: Exact match (=) > Strong prefix match (^~) > Regular expressions (~, ~*) > Ordinary prefix match > Generic match (/).
• Whether proxy_pass includes a trailing slash affects path forwarding behavior.
• It is recommended to centralize map directives in a separate maps.conf file to avoid variable overwriting caused by file loading order.
• When mounting configuration files using Docker, it is recommended to add :ro (read-only) to protect the configuration files, while keeping write permissions for the log directory.
• After modifying the configuration, always run nginx -t to check the syntax before using nginx -s reload to reload, preventing service interruption.
• If you need to dynamically configure Nginx using environment variables, you can use the Template feature of the official image, but the container must be restarted after modifying the variables.

Nginx Architecture and Configuration Hierarchy

Nginx configuration files consist of multiple Contexts, with each block corresponding to different levels of configuration:

• Main Context: The outermost layer, defining global parameters (e.g., number of workers, user permissions).
• Events Context: Defines connection processing parameters (e.g., worker_connections).
• HTTP Context: Defines global HTTP server settings (e.g., MIME types, log formats).

Location Block Matching Rules

When to encounter this issue: When you need to define complex routing rules and are unsure which location block will handle the request.

Location supports various matching modifiers, with the following priority:

1. Exact match =: Matches only if identical (highest priority).
2. Strong prefix match ^~: Stops searching for regular expressions after a successful prefix match.
3. Regular expression (case-sensitive) ~: Used in the order of definition.
4. Regular expression (case-insensitive) ~*: Used in the order of definition.
5. Ordinary prefix match: The longest match takes priority.
6. Generic match /: Default rule (lowest priority).

WARNING

If both location /test and location ^~ /test are defined, Nginx will report an error due to rule conflict.

Proxy Pass and Path Handling

When to encounter this issue: When you find that the path received by the backend does not match expectations during reverse proxy forwarding.

Whether the URI of proxy_pass includes a trailing slash affects forwarding behavior:

• No trailing slash: Full forwarding.
  • proxy_pass http://backend;
  • Request /app/test -> Forwarded to http://backend/app/test
• With trailing slash: Performs path replacement.
  • proxy_pass http://backend/;
  • Request /app/test -> Forwarded to http://backend/test

Configuration Management Recommendations

File Structure and Map Sharing

When to encounter this issue: When the project scale grows and configuration files are scattered across multiple files, leading to variable definition conflicts.

map variables defined in the http block are global. Since Nginx loads conf.d/*.conf in alphabetical order, if multiple files define map variables with the same name, the later one will overwrite the former. It is recommended to centralize all map definitions in maps.conf.

Docker Mounting and Read-Only Permissions

When to encounter this issue: When you want to ensure that configuration files inside the container are not accidentally tampered with, or when you need to handle log writing correctly.

When mounting configuration files in compose.yaml, it is recommended to use the :ro (read-only) flag:

volumes:
  - ./volumes/config/conf.d:/etc/nginx/conf.d:ro
  - ./volumes/logs:/var/log/nginx

• :ro (read-only): Suitable for configuration files to prevent processes inside the container from accidentally modifying host files.
• No :ro: Suitable for log directories, upload directories, or cache directories, as Nginx must have write permissions.

Verification and Reloading

When to encounter this issue: When you are worried that syntax errors might cause the service to crash after modifying the Nginx configuration.

Please follow this standard procedure:

1. Test syntax: docker compose exec nginx nginx -t
2. Reload: docker compose exec nginx nginx -s reload

Using Templates to Handle Environment Variables

When to encounter this issue: When you need to dynamically adjust Nginx settings based on different environments (e.g., development, testing, production).

The official Nginx image (1.19+) supports the Template feature. By placing .template files into /etc/nginx/templates, environment variables will be automatically replaced when the container starts.

TIP

When using the Template method, environment variable replacement only occurs when the container starts. After modifying environment variables, you must execute docker compose up -d to restart the container; updates cannot be performed via nginx -s reload.

Changelog

• 2025-11-27 Initial document created.